24장 Claude Squad 살펴보기 (입문판)

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 3가지만 기억하세요. 1. Claude Squad는 여러 작업을 동시에 굴리게 도와주는 터미널 앱이다. 2. 설치는 tmux와 GitHub CLI를 먼저 깔고, 그다음 Claude Squad 본체를 깐다. 3. 사용은 키 몇 개로 끝난다 — N으로 만들고, Enter로 들어가고, Ctrl+Q로 나오고, P로 푸시한다.

들어가기 전에

이 장은 서드파티 도구 소개입니다. Claude Squad는 앤트로픽이 만든 게 아니라, 외부 개발자들이 만든 오픈소스 도구예요.

그래서 이 장의 설치 명령이나 단축키는 원서 작성 시점 기준 예시입니다. 실제로 깔 때는 공식 저장소에서 최신 설치법을 한 번 더 확인하는 게 안전합니다.

이 장에서 쓰는 도구 공식 이름: Claude Squad, tmux, GitHub CLI, Git Worktree. 이 이름들만 쓸게요. 비슷한 줄임말이나 별명은 안 씁니다.

이 장을 따라가려면 앞에서 배운 것 몇 가지가 필요해요. Git의 브랜치, 커밋, 푸시가 뭔지. 터미널에 명령어를 치는 기본 사용법. 클로드 코드 기본 사용법. 이 정도만 알면 충분합니다.

24-1 Claude Squad란?

학습 목표

이 절을 마치면 이런 걸 할 수 있어요.

• Claude Squad가 어떤 문제를 풀어주는지 설명한다.
• 수동으로 여러 작업을 하는 것과 Claude Squad를 구분한다.

이런 적 있죠?

여러분이 프로젝트를 하나 하고 있다고 해볼게요. 화면 디자인도 손보고 싶고, 데이터베이스도 정리하고 싶어요.

그래서 두 가지를 한 브랜치에서 같이 건드렸어요. 그랬더니 코드가 서로 엉켰습니다. 디자인 고치다 만 코드 위에 데이터베이스 코드가 덮였어요. 나중에 디자인만 되돌리고 싶은데, 둘이 섞여서 못 떼어냅니다.

"하나 끝내고 다음 거 해야겠다" 하고 순서대로 했더니 이번엔 너무 느려요. 하나 끝날 때까지 다른 일은 손도 못 댑니다.

이게 바로 "작업이 서로 충돌하고, 동시에 못 한다"는 문제예요. 그리고 이 문제를 풀어주는 게 Claude Squad입니다.

그래서 Claude Squad가 뭐냐면

Claude Squad는 여러 클로드 코드를 동시에 굴리고 한 화면에서 관리해 주는 터미널 앱이에요. 화면 작업용 클로드 코드 하나, 데이터베이스 작업용 클로드 코드 하나. 이렇게 따로따로 돌려서 서로 안 섞이게 해 줍니다.

새 용어 하나 짚고 갈게요. Git Worktree는 "한 저장소 안에서 작업 폴더를 여러 개 만드는 Git 기능"이에요. 일상 비유로는, 한 권의 책을 베껴 쓸 때 복사본 노트를 여러 권 만들어 각자 다른 챕터를 쓰는 것과 같아요. 원본은 그대로 두고 복사본에서만 작업하니까 안 섞입니다.

또 하나. tmux는 "터미널 하나에서 여러 화면을 만들고 왔다 갔다 하게 해주는 도구"예요. 일상 비유로는, 모니터 하나에 창을 여러 개 띄워 놓고 알트탭으로 전환하는 것과 같아요.

Claude Squad는 이 두 가지(Git Worktree와 tmux)를 묶어서, 여러분이 직접 안 만져도 알아서 굴려 줍니다.

비유로 한 번에 정리

수동으로 하면 이렇게 됩니다 (잘못된 예 vs 올바른 예)

상황: 화면 개선과 데이터베이스 정리를 같이 하고 싶다.

잘못된 예 — 워크트리를 손으로 다 한다.

git worktree add ../improve-ui
cd ../improve-ui
claude
# 다른 터미널 창을 또 연다
git worktree add ../migrate-db
cd ../migrate-db
claude
# 어느 창이 무슨 작업이었는지 헷갈리기 시작한다

올바른 예 — Claude Squad에 맡긴다.

cs
# N 눌러서 improve-ui 만들고
# N 눌러서 migrate-db 만들고
# J/K로 왔다 갔다 하면서 관리한다

손으로 하면 명령어를 매번 치고 창도 여러 개 관리해야 해요. Claude Squad는 키 한두 개로 끝납니다.

이럴 때 이렇게: "동시에 두세 가지 작업을 굴려야 하는데 서로 안 섞였으면 좋겠다" 싶으면 Claude Squad를 떠올리세요.

꼭 기억할 점

• Claude Squad는 화면 클릭하는 프로그램(GUI)이 아니라 터미널에서 키로 쓰는 도구예요.
• 각 작업은 따로 만든 워크트리에서 돌아서, 메인 브랜치(원본)에 영향을 안 줍니다.
• 원서 작성 시점 기준으로 macOS에서 쓰는 것으로 소개됩니다. 환경 지원 범위는 공식 저장소에서 확인하세요.
• 오픈소스라서 누구나 코드를 볼 수 있어요. 공식 저장소는 github.com/smtg-ai/claude-squad 입니다.

24-2 Claude Squad 설치하기

학습 목표

이 절을 마치면 이런 걸 할 수 있어요.

• 설치에 앞서 무엇을 먼저 깔아야 하는지 설명한다.
• 설치 명령을 순서대로 따라 한다.

이런 적 있죠?

새 앱을 깔았는데 "실행하려면 다른 프로그램이 먼저 필요합니다"라는 말을 본 적 있을 거예요. 게임을 깔았더니 그래픽 도구를 먼저 깔라고 하는 것처럼요.

Claude Squad도 그래요. 혼자서는 못 돌고, 두 가지 도구가 먼저 깔려 있어야 합니다. 이 "먼저 필요한 도구"를 사전 준비라고 부를게요.

먼저 깔아야 하는 두 가지

Claude Squad는 tmux와 GitHub CLI 위에서 돌아갑니다.

tmux는 아까 봤죠. 터미널 하나에서 여러 화면을 굴리는 도구예요. Claude Squad가 여러 작업을 한 화면에 띄우려면 이게 필요합니다.

GitHub CLI는 "터미널에서 GitHub를 다루는 공식 도구"예요. 명령어가 gh로 시작합니다. 일상 비유로는, 웹사이트에 들어가 버튼을 누르는 대신 말로 시키는 비서 같은 거예요. Claude Squad의 푸시 기능을 쓰려면 이게 있어야 합니다.

설치 위치는 각 공식 사이트입니다.

tmux 설치 안내      : github.com/tmux/tmux/wiki/Installing
GitHub CLI 설치 안내 : cli.github.com

Claude Squad 본체 설치 (두 가지 방법 중 하나)

사전 준비가 끝났으면 Claude Squad를 깝니다. 방법이 두 가지인데, 둘 중 편한 걸 하나 고르면 돼요.

방법 1 — Homebrew로 설치.

새 용어 하나. Homebrew는 "macOS에서 프로그램을 명령어로 깔게 해주는 설치 도우미"예요. 일상 비유로는, 휴대폰 앱스토어를 명령어로 쓰는 거랑 비슷해요.

brew install claude-squad
ln -s "$(brew --prefix)/bin/claude-squad" "$(brew --prefix)/bin/cs"

첫 줄이 본체 설치예요. 둘째 줄은 긴 이름 claude-squad를 짧은 cs로도 부를 수 있게 만드는 거예요.

여기서 ln -s가 뭐냐면, "바로가기를 만드는 명령"이에요. 일상 비유로는, 바탕화면에 프로그램 바로가기 아이콘을 만드는 것과 같아요. 이 바로가기를 심볼릭 링크라고 불러요. 이걸 만들어 두면 매번 claude-squad라고 길게 안 치고 cs만 쳐도 실행됩니다.

방법 2 — curl 스크립트로 설치.

curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash

이건 설치 스크립트를 인터넷에서 받아 바로 실행하는 방식이에요. 한 줄로 끝나서 간편합니다.

한 걸음 더 ▸ 위 명령들은 원서/노트 기준 예시입니다. 서드파티 도구라서 설치 방법이 바뀔 수 있어요. 실제로 깔 때는 공식 저장소(github.com/smtg-ai/claude-squad)에서 최신 설치법을 확인하세요. 인터넷에서 받은 스크립트를 바로 실행하는 건 편하지만, 출처가 믿을 만한지 한 번 보고 하는 습관이 좋아요.

설치가 잘 됐는지 확인하기

설치가 끝났으면 터미널에 cs라고 쳐 보세요. 아래 같은 화면이 뜨면 성공입니다.

     Preview                          Diff
  +--------------------------------------------+
  |                                            |
  |              SQUAD                          |
  |                                            |
  |  No agents running yet.                    |
  |  Spin up a new instance with 'n'           |
  |  to get started!                           |
  +--------------------------------------------+

화면 아래 단축키:
  n new | N new with prompt | ? help | q quit

"No agents running yet"는 "아직 돌아가는 작업이 없어요"라는 뜻이에요. "Spin up a new instance with 'n'"은 "n 키로 새 작업을 만들어 시작하세요"라는 안내예요. 즉, 이 화면이 뜨면 설치는 끝난 거고 이제 쓰기만 하면 됩니다.

잘못된 예 vs 올바른 예

잘못된 예 — 사전 준비 없이 바로 본체부터 깐다.

# tmux도 GitHub CLI도 없이
brew install claude-squad
# 나중에 푸시 기능 쓰려다 gh 없다고 막힌다

올바른 예 — 순서대로 한다.

# 1) tmux 설치
# 2) GitHub CLI 설치
# 3) Claude Squad 설치 (Homebrew 또는 curl)
# 4) cs 입력해서 화면 확인

이럴 때 이렇게: 설치 후 cs를 쳤는데 화면이 안 뜨거나 명령을 못 찾는다고 나오면, 보통 사전 준비(tmux, GitHub CLI)나 cs 바로가기가 빠진 경우예요. 순서부터 다시 확인하세요.

꼭 기억할 점

• tmux와 GitHub CLI는 먼저 깔아야 하는 필수 도구예요.
• 본체 설치는 Homebrew와 curl 두 방법 중 하나면 됩니다.
• 설치 후엔 cs 명령으로 실행해요.
• ln -s는 claude-squad를 짧은 cs로 부르려고 만드는 바로가기(심볼릭 링크)예요.

24-3 Claude Squad 사용법

학습 목표

이 절을 마치면 이런 걸 할 수 있어요.

• 작업을 만들고 들어갔다 나오는 과정을 따라 한다.
• 변경 사항을 확인하고 푸시하는 흐름을 설명한다.

이런 적 있죠?

여러 일을 동시에 할 때, 일을 만들고 들어가고 나오는 게 헷갈린 적 있죠. 어느 창이 무슨 작업이었는지 잊어버리고요.

Claude Squad는 이걸 키 몇 개로 정리해 줍니다. 만들기, 들어가기, 나오기, 확인하기, 푸시하기. 이 다섯 동작만 익히면 끝이에요.

새 용어 두 가지

인스턴스는 "Claude Squad가 만든 하나의 작업 단위"예요. 워크트리 하나 + 클로드 코드 세션 하나가 묶인 거예요. 일상 비유로는, 책상 하나에 노트 한 권과 일꾼 한 명이 세트로 앉아 있는 거예요. 작업을 새로 만들면 인스턴스 하나가 생긴다고 보면 됩니다.

Diff는 "코드가 어떻게 바뀌었는지 보여주는 화면"이에요. 일상 비유로는, 문서 편집기의 "변경 내용 추적"처럼 뭐가 추가되고 뭐가 지워졌는지 표시해 줘요. 추가된 줄은 더하기, 지워진 줄은 빼기로 보입니다.

7단계 워크플로 (안전한 길)

기본 흐름은 7단계예요. 천천히 따라가 봅시다.

1단계 — 프로젝트 폴더에서 cs를 실행해요. 그러면 Claude Squad 대시보드(전체 화면)가 열립니다.

2단계 — N 키로 새 작업을 만들어요. 기능 이름을 입력합니다 (예: improve-ui). 그러면 독립된 워크트리가 자동으로 생겨요. 화면에 워크트리 경로가 노란 글자로 표시됩니다.

3단계 — Enter로 그 작업에 들어가요. 클로드 코드 터미널이 전체 화면으로 열립니다. 평소 쓰던 클로드 코드랑 똑같이 쓰면 돼요.

4단계 — Ctrl+Q로 그 작업에서 나와요. 대시보드로 돌아옵니다. 중요한 건, 나와도 그 작업은 뒤에서 계속 돌아가요(백그라운드 실행).

5단계 — N 키로 작업을 하나 더 만들어요. 새 워크트리와 인스턴스가 또 생깁니다. J/K 키로 작업 사이를 오갈 수 있어요 (J는 아래, K는 위).

6단계 — Tab 키로 Diff 화면을 확인해요. 각 작업에서 코드가 어떻게 바뀌었는지 한눈에 봅니다. 추가(+)와 삭제(-)가 표시돼요.

7단계 — P 키로 푸시해요. P 누르고 Y로 확인하면, 커밋하고 GitHub 저장소에 올라갑니다.

키보드 단축키 — 전부 모아 보기

대시보드 화면에서 쓰는 키예요.

n      새 작업 만들기 (기본)
N      프롬프트와 함께 새 작업 만들기
Enter  고른 작업에 들어가기
J      아래 작업으로 이동
K      위 작업으로 이동
Tab    Preview 화면 <-> Diff 화면 전환
D      작업 삭제 (없애기)
P      변경 사항 푸시
c      체크아웃
w / o  열기
?      도움말
q      종료

작업 안에 들어가 있을 때 쓰는 키예요.

Ctrl+Q  작업에서 나가기 (뒤에서 계속 실행됨)

여기서 Preview는 "지금 고른 작업의 터미널 화면을 실시간으로 보여주는 탭"이에요. Tab 키를 누르면 Preview와 Diff를 번갈아 볼 수 있어요. Preview로는 작업이 지금 뭐 하는지 보고, Diff로는 코드가 어떻게 바뀌었는지 봅니다.

n과 N은 둘 다 새 작업을 만드는데, N은 처음부터 시킬 말(프롬프트)을 같이 넣어 만드는 거예요.

잘못된 예 vs 올바른 예

상황: 작업을 잠깐 멈추고 다른 작업을 보고 싶다.

잘못된 예 — 작업을 끝내려고 클로드 코드를 그냥 종료한다.

# 작업 안에서 클로드 코드를 닫아버린다
# -> 돌아가던 작업이 멈춰버린다

올바른 예 — Ctrl+Q로 나간다.

Ctrl+Q
# 대시보드로 돌아오고, 그 작업은 뒤에서 계속 돌아간다
# 나중에 J/K로 다시 그 작업으로 돌아가면 된다

Ctrl+Q는 "끄기"가 아니라 "잠깐 나오기"예요. 일을 멈추지 않고 화면만 빠져나오는 거라, 다른 작업을 보다가 다시 돌아올 수 있어요.

이럴 때 이렇게: 작업 두 개를 번갈아 보고 싶다면, 한쪽에서 Ctrl+Q로 나온 뒤 J/K로 다른 쪽으로 이동하세요. 작업은 양쪽 다 계속 돌아갑니다.

미니 시나리오 — 로그인 개선 + 대시보드 리디자인

상황: 로그인 기능 개선과 대시보드 리디자인을 같이 하고 싶다.

1. 프로젝트 폴더에서 cs 실행
2. N -> "login-improvement" 입력 -> Enter  (첫 워크트리 생성)
3. Enter로 들어가 클로드 코드에게 로그인 개선 지시
4. Ctrl+Q로 나오기 (뒤에서 계속 실행)
5. N -> "dashboard-redesign" 입력 -> Enter  (둘째 워크트리 생성)
6. Enter로 들어가 클로드 코드에게 대시보드 리디자인 지시
7. Ctrl+Q로 나와서 J/K로 두 작업 둘러보기
8. Tab으로 Diff 확인 -> 다 되면 P -> Y로 각각 푸시

두 작업이 각자 다른 워크트리에서 돌기 때문에 서로 안 섞여요. 하나가 망가져도 다른 하나는 멀쩡합니다.

한 걸음 더 ▸ 다 끝난 작업은 D 키로 지울 수 있어요. 손으로 워크트리를 정리하지 않아도 D 한 번이면 됩니다. 그리고 c(체크아웃), w/o(열기) 같은 키도 있는데, 처음엔 안 써도 괜찮아요. 기본 흐름(만들기-들어가기-나오기-확인-푸시)부터 익숙해진 다음에 천천히 써 보세요.

꼭 기억할 점

• 작업을 만들면 메인 브랜치와 완전히 분리된 워크트리가 생겨요.
• Ctrl+Q로 나와도 그 작업은 뒤에서 계속 돌아가요.
• Claude Squad를 끄지 않으면 언제든 돌아와서 확인할 수 있어요.
• Diff 화면에서 각 작업의 코드 변경을 한눈에 봐요.
• P 키 다음 Y 키로 바로 커밋하고 GitHub에 푸시해요.
• 합치기(머지) 전까지는 메인 브랜치에 영향을 안 줘요.

한눈에 보는 비교표

손으로 워크트리 관리 vs Claude Squad

손으로 하면 명령어를 매번 쳐야 하고, Claude Squad는 키 한 번씩이면 됩니다.

연습문제

문제 1

Claude Squad가 안에서 쓰는 두 가지 핵심 도구는 무엇이고, 각각 무슨 일을 하나요?

문제 2

"로그인 개선과 대시보드 리디자인을 같이 하고 싶다." Claude Squad로 처리하는 순서를 적어 보세요.

문제 3

Claude Squad 없이 Git Worktree만 손으로 쓸 때 불편한 점 3가지를 적어 보세요.

부록 — 용어 사전

참고 자료

서드파티 도구라 설치법·옵션은 바뀔 수 있어요. 위 공식 저장소에서 최신 정보를 확인하세요.

다음 장 예고: 다음 장에서는 또 다른 도구를 살펴봐요. 지금 몰라도 됩니다.